
This drawer contains a generic install script.  If you are creating a
WHDLoad install you should use it. Only small adjustments are required to
get a system conformable, user friendly and well tested install package.


Step by Step to create the install package:
*******************************************

* First copy the whole directory 'Xxx Install' + the drawer icon 'Xxx
  Install.info' to a different location of your choice (using the Workbench
  or some directory commander). The 'Xxx Install' will become your top level
  directory of the installation package.

* Now rename the directory/drawer icon 'Xxx Install', replace Xxx with the
  name of the program to be installed. It is recommended to give it the same
  basename as your Slave (ISlave, Imager, etc.), e.g. "HeroQuest7 Install",
  the basename should not contain spaces, underlines, special chars, roman
  numbers and shouldn't be too long.

* The next step is to set the APPNAME in the install icon. The APPNAME must
  be set to the basename. It is used be the install script to refer to the
  Slave/ISLave/Imager and all the icons. All these files should start with
  the same basename. If they do not, you have to overwrite the defaults in
  the install script which is extra work. You may also change the tooltype
  MINUSER to NOVICE if your install will only copy files from named disks.
  If you use DIC, RawDIC or Patcher leave it at AVERAGE. Otherwise the user
  gets not asked necessary questions.

* Now you have to copy all your installation files. The install template
  contains dummies for them which are named 'Example.#?', these should
  remember you about the files required. Some files are only useful on
  specific types of installs. E.g. you need a #?.ISlave only when RawDIC is
  used.
  Copy your #?Slaves's and your icons to the directory and then delete all
  Example.#? files.

* The next step is to edit the install script called 'Install'. Open it in
  your prefered editor.
  THERE IS NO NEED TO DELETE ANYTHING FROM THE SCRIPT! All can be adjusted
  to your needs by setting some variables in the script. Minimal changes
  will make later changes or enhancements (e.g. supporting more than one
  version of the program to install) much easier.
  Most times it is enough to set #version to the type of your install
  process. Then scroll down to the procedure 'P_MakeImages' and find the
  section appropriate for your install type. Depending on the amount of disks
  (DIC) or names of the files to copy you must adpapt it. For the install
  types RawDIC and Patcher you only have to set the varible '#last-file'.
  Nothing else have to be changed when using default naming conventions.
  For extra features see more detailed infos below...

* As the last step you have to create the ReadMe for your install. You can
  freely design that. The one contained in the template is an example.
  The ReadMe should at least contain the requirements to use the install
  and a version log with changes and timestamps.

* When completed you should test your script properly. If there are muliple
  versions supported test all of them. Make sure it installs correctly to
  directories containing spaces (e.g. "Ram Disk").

* For public release on www.whdload.de archive your install using lha.
  The archive should be named using the basename of the install e.g.
  "HeroQuest7.lha", if it is a install for a demo the group name should
  be prepended e.g. "Silents_HeroQuest7.lha".



Adapting the install script
***************************

HEADER VARIABLES
----------------

	- set #multiple-versions to anything other than an empty string if
	  the install supports multiple versions

	- set #sub-dir if you want to use a sub directory for all game files

	- set #highs-file to the relevant name to copy a default high-score
	  file into the games directory


SELECTING A VERSION
-------------------

	- if there are multiple versions, change "P_SelectVersion" to list
	  the different releases in the order you wish them to appear. 

	- you may also setup a suffix for any version which is appended to
	  the slave name and directory.

	  eg. Jungle Strike has 3 different slaves for different memory
	  configurations and WHDLoad flags. It installs in the directory
	  "JungleStrike", "JungleStrikeAGA" or "JungleStrikeCD32". The
	  default is "JungleStrike" and the suffix "AGA" or "CD32" can be 
	  added by setting the #version_suffix. Most of the time this is
	  NOT required!


COPYING/INSTALLING FILES
------------------------

	- change "P_MakeImages" to move the relevant file-copy routine into
	  position. eg. if you have a DIC install, move the DIC section to
	  the top of the routine (instead of RawDIC)

	- if you need to decrunch any file(s), uncomment the XFD decrunch
	  section and move it into the relevant position for each version


MULTIPLE SLAVES/ICONS
---------------------

	- if the install supports multiple slaves, alter "P_MakeIcons" which
	  copies the slave and asks the user to select the relevant icon.

	  eg. You can have an intro slave with choice of intro icon, and a
	  game slave with choice of game icon. 

	- if the intro shares the same slave as the game, you do not need to 
	  call "P_CopySlave" (eg. when the intro uses the same slave as the 
	  game but perhaps has CUSTOM1=1 to skip the intro in the games icon)


GENERAL
-------
	- change APPNAME in the Installer icon to the name of the program
	  to install

	- replace the #?.slave and #?.inf with yours

	- adjust the README for your needs

	- file naming conventions:
		slave				APPNAME + ".slave"
		normal icon			APPNAME + ".inf"
		magicwb icon			APPNAME + ".magicwb"
		romicon				APPNAME + ".romicon"
		newicon				APPNAME + ".newicon"
		newicon by exotica		APPNAME + ".newexot"
		OS3.5 colour icon		APPNAME + ".colicon"
		OS3.5 colour icon by exotica	APPNAME + ".colexot"
		boxicon				APPNAME + ".boxicon"

	  there are also spare slots in the templates for any other icons 
	  you wish to install

	- if multiple icons are found, the user will be asked during the 
	  installation process which icon to install (with a picture preview
	  option if using a new enough version of Installer)

        - Optional: if the game has got a name with spaces or special chars and
          you don't want the game directory/slave/icons to have the same name,
          you can change the #prefix variable at the beginning of the install script
          Example: APPNAME = Prince Of Persia => (set #prefix "PrinceOfPersia")


SPECIFIC INSTALL TYPES
----------------------

DIC - for standard disk images:

	- move the DIC section to the top of the "P_MakeImages" function

	- the procedure "P_MakeImages" near the top of the install script 
	  must be changed depending on the number of disks

	- if there is on-disk protection (e.g. RN-Copylock on track 1) the
	  appropriate track must be marked to skip by DIC using the variable
	  "#CI_skiptrk"

	- the length of the images to create can be set using the variable
	  "#CI_disklen"


RawDIC - for custom disk formats:

	- set #last-file in the RawDIC section to the name of the last file
	  created by RawDIC (which is used to check for success)

	- additional file naming conventions:
		imager		APPNAME + ".islave"


Patcher - for custom disk formats:

	- set #last-file in the Patcher section to the name of the last file
	  created by Patcher (which is used to check for success)

	- additional file naming conventions:
		imager		APPNAME + ".islave"


Std-Files - for standard Amiga Filesystem disks:

	- move the DOS version (Files) section to the top of the 
	  "P_MakeImages" function

	- alter the disk names as appropriate (by setting #AD_disk)

	- alter the source and pattern as needed to copy the files. If you
	  want to copy all files, remove the (pattern) section and put (all)


CD-Version - for standard CD Filesystem discs:

	- move the CD version (Files) section to the top of the 
	  "P_MakeImages" function

	- alter the source and pattern as needed to copy the files. If you
	  want to copy all files, remove the (pattern) section and put (all)


DOS Version - for a single file selection (useful when disk name is unknown)

	- this version is useful when a game is installed from an archive on
	  aminet or requires the user to select a specific file which can
	  be named as something different (eg. on compact discs, the Rick
	  Dangerous file maybe called "1", "Rick", "RickD" etc)

	- move the DOS version (Single file) section to the top of the 
	  "P_MakeImages" function

	- alter the #SF_default_filename and #SF_new_filename as required - 
	  the file the user selects will always be renamed to 
	  #SF_new_filename no matter what file they selected



EXAMPLES
--------

FOOTBALL MANAGER: WORLD CUP EDITION (DIC - 1 DISK)

	- move the DIC section to the top of the "P_MakeImages" function

	- remove the second disk imaging routine because the game is only
	  1 disk

	- set #CI_skiptrk to 1 to skip the copylock track


CAVEMANIA (MFM DISK VERSION AND CRACKED FILES VERSION - 1 DISK)

	- Set multiple versions to true at the very top:
	    (set #multiple-versions "true")

	- alter "P_SelectVersion" to show the relevant supported versions:
            (choices "Original release" "Quartex crack")

	- alter "P_MakeImages" by putting the RawDIC and DOS version (Files)
	  sections at the top of the routine

	- set the "#last-file" variable for the RawDIC version

	- alter the file copying section for the Quartex cracked version

	- the icons have not been setup in advance with Slave=CaveMania.slave
	  and Preload, so we will get the installer to do that by changing
	  the routine "P_MakeIcons":
	    (set #icon_set_slave_preload "true")


SUPERFROG (DISK VERSION AND CD32 VERSION WITH SEPARATE SLAVES)

	- Superfrog installs 2 icons for the install (intro and game).
	  Game has 2 slaves, Superfrog.slave and SuperfrogCD32.slave.
	  Intro has 2 slaves, Intro.slave and IntroCD32.slave

	- set multiple versions to true at the very top:
	    (set #multiple-versions "true")

	- setup the multiple version name choices:
	    (choices "Disk version" "CD32 version")

	- setup the version suffix (so it is "Superfrog" for the normal 
	  version and "SuperfrogCD32" for the CD32 version):
	    (select #version
	      ()				;Normal version
	      (set #version_suffix "CD32")	;CD32 version
	    )

	- we are supporting the RawDIC slave and the CD32 files version, 
	  so move those 2 sections so they are at the top of "P_MakeImages"

	- RawDIC version will produce 3 files, "Disk.1", "Disk.2" and 
	  "Disk.3" so setup the last file that should be created:
	    (set #last-file "Disk.3")

	- CD32 version needs to copy all files from the data subdirectory:
	    (copyfiles
	      (help @copyfiles-help)
	      (source "Superfrog_AGA:data")
	      (dest #dest)
	      (all)
	    )

	- We are installing 2 icons for the game: "SuperfrogIntro.slave" and
	  "Superfrog.slave" (disk version) and "SuperfrogIntroCD32" and
	  "SuperfrogCD32.slave" (CD32 version). We need to get the installer
	  to setup the correct Slave names and Preload because we do not
	  know if they have picked the disk version or the CD32 version 
	  until now:

	    (procedure P_MakeIcons
	      (set #icon_desc "intro")
	      (set #icon_prefix ("%s%s" "SuperfrogIntro" #version_suffix))
	      (set #icon_slave #icon_prefix)
	      (set #icon_set_slave_preload "true")
	      (set #icon_set_deftool_stack "true")
	      (P_CopySlave)
	      (P_SelectIcon)

	      (set #icon_desc "game")
	      (set #icon_prefix #prefix)
	      (set #icon_slave #icon_prefix)
	      (set #icon_set_slave_preload "true")
	      (set #icon_set_deftool_stack "true")
	      (P_CopySlave)
	      (P_SelectIcon)
	    )
